using RAG.Application.Dtos;
using RAG.Application.Commands;

namespace RAG.Application.Interfaces;

/// <summary>
/// 文档服务接口
/// </summary>
public interface IAppDocumentService
{
    /// <summary>
    /// 上传文档
    /// </summary>
    Task<ApiResult> UploadDocumentAsync(UploadDocumentDto dto);
    
    /// <summary>
    /// 获取文档列表
    /// </summary>
    Task<ApiResult> GetDocumentsAsync(Guid userId, Guid? knowledgeBaseId = null);
    
    /// <summary>
    /// 获取文档详情
    /// </summary>
    Task<ApiResult> GetDocumentAsync(Guid documentId);
    
    /// <summary>
    /// 删除文档
    /// </summary>
    Task<ApiResult> DeleteDocumentAsync(Guid documentId, Guid userId);
    
    /// <summary>
    /// 更新文档
    /// </summary>
    Task<ApiResult> UpdateDocumentAsync(UpdateDocumentDto dto);
    
    /// <summary>
    /// 更新文档状态
    /// </summary>
    Task<ApiResult> UpdateDocumentStatusAsync(Guid documentId, string status);
    
    /// <summary>
    /// 搜索文档
    /// </summary>
    Task<ApiResult> SearchDocumentsAsync(SearchDocumentsDto dto);
    Task<ApiResult> BatchUploadDocumentsAsync(BatchUploadDocumentsDto dto);
    Task<ApiResult> UpdateDocumentPermissionsAsync(UpdateDocumentPermissionsDto dto);
    
    /// <summary>
    /// 获取文档的文档块列表
    /// </summary>
    Task<ApiResult> GetDocumentChunksAsync(Guid documentId);
    
    /// <summary>
    /// 重新处理文档（重新分块和向量化）
    /// </summary>
    Task<ApiResult> ReprocessDocumentAsync(Guid documentId);
    
    /// <summary>
    /// 下载文档
    /// </summary>
    Task<ApiResult> DownloadDocumentAsync(Guid documentId, Guid userId);

    /// <summary>
    /// 当原始文件缺失时，根据文档分块内容动态生成文本文件用于下载
    /// 返回值为三元组：(文件字节数组, Content-Type, 下载文件名)。如果无法生成则返回 null。
    /// </summary>
    Task<(byte[] bytes, string contentType, string fileName)?> GenerateTextFromChunksAsync(Guid documentId, Guid userId);
}
